# performance.bundleAnalyze

- **类型：** `Object | undefined`

用于开启 [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) 插件来分析产物体积。

默认情况下，Rsbuild 不会开启 `webpack-bundle-analyzer`。当开启该功能后，内部的默认配置如下:

```js
const defaultConfig = {
  analyzerMode: 'static',
  openAnalyzer: false,
  // 通过 environment 名称区分，如 `web`、`node` 等
  reportFilename: `report-${environment}.html`,
};
```

## 启用 Bundle analyze

你有两种方式开启 `webpack-bundle-analyzer` 来分析构建产物的体积。

### 通过环境变量

添加环境变量 `BUNDLE_ANALYZE=true`，比如：

```json title="package.json"
{
  "scripts": {
    "build:analyze": "BUNDLE_ANALYZE=true rsbuild build"
  }
}
```

由于 Windows 不支持上述用法，你也可以使用 [cross-env](https://npmjs.com/package/cross-env) 来设置环境变量，这可以确保在不同的操作系统中都能正常使用：

```json title="package.json"
{
  "scripts": {
    "build:analyze": "cross-env BUNDLE_ANALYZE=true rsbuild build"
  },
  "devDependencies": {
    "cross-env": "^7.0.0"
  }
}
```

### 通过配置项

配置 `performance.bundleAnalyze` 来固定开启：

```ts title="rsbuild.config.ts"
export default {
  performance: {
    bundleAnalyze: {},
  },
};
```

### 分析结果

在启用后，Rsbuild 会生成一个分析构建产物体积的 HTML 文件，并在 Terminal 中打印以下日志：

```bash
Webpack Bundle Analyzer saved report to /Project/my-project/dist/report-web.html
```

手动在浏览器中打开该文件，可以看到打包产物的瓦片图；区块的面积越大，说明该模块的体积越大。

![](https://assets.rspack.rs/rsbuild/assets/bundle-analyzer-example.png)

## 覆盖默认配置

你可以通过 `performance.bundleAnalyze` 来覆盖默认配置，比如开启 `server` 模式：

```ts title="rsbuild.config.ts"
export default {
  performance: {
    bundleAnalyze: process.env.BUNDLE_ANALYZE
      ? {
          analyzerMode: 'server',
          openAnalyzer: true,
        }
      : {},
  },
};
```

## Size 类型

在 `webpack-bundle-analyzer` 的面板中，你可以在左上角控制 Size 类型（默认为 `Parsed`）：

- `Stat`：从打包工具的 `stats` 对象中获取的体积，它反映了代码在压缩之前的体积。
- `Parsed`：磁盘上的文件体积，它反映了代码在压缩之后的体积。
- `Gzipped`：浏览器里请求的文件体积，它反映了代码在压缩和 gzip 后的体积。

## 生成 stats.json

`generateStatsFile` 设置为 true 时，将会生成 stats JSON 文件。

```ts title="rsbuild.config.ts"
export default {
  performance: {
    bundleAnalyze: {
      generateStatsFile: true,
    },
  },
};
```

在产物目录下会生成 `stats.json` 和 `report-web.html` 文件。

```
└── dist
    ├── stats.json
    └── report-web.html
```

如果你不需要 `report-web.html`，可以设置 `analyzerMode` 为 `disabled`。

```ts title="rsbuild.config.ts"
export default {
  performance: {
    bundleAnalyze: {
      analyzerMode: 'disabled',
      generateStatsFile: true,
    },
  },
};
```

## 注意事项

1. 开启 Server 模式会导致 `build` 进程不能正常退出。
2. 开启 bundleAnalyzer 会降低构建性能。因此，在日常开发过程中不应该开启此配置项，建议通过 `BUNDLE_ANALYZE` 环境变量来按需开启。
3. 由于 `dev` 阶段不会进行代码压缩等优化，无法反映真实的产物体积，因此建议在 `build` 阶段分析产物体积。
4. 如果在 `dev` 阶段开启 bundleAnalyzer，为了保证 webpack-bundle-analyzer 可以读取到静态资源的内容，Rsbuild 会自动开启 [dev.writeToDisk](/config/dev/write-to-disk) 选项。
